import { Table } from 'nextra/components'
import { LogoImage, TrustedBy } from '@/components'

<div className="my-20 px-12 md:my-40 md:px-24">
  <LogoImage size={2.4} />
</div>

Suspensive is a comprehensive collection of libraries designed to simplify and enhance the use of React Suspense. Suspensive contains several packages that provide components, hooks, and utilities to streamline the implementation of suspense-based features, error handling, and integrations with popular data fetching libraries.

## Purpose

The Suspensive libraries address common challenges developers face when working with React Suspense, such as:

- Managing loading states and timing
- Implementing robust error boundaries
- Integrating suspense with data fetching libraries
- Coordinating multiple suspense and error boundaries
- Creating viewport-aware components with suspense capabilities

By providing a unified, declarative API for these concerns, Suspensive helps developers create more resilient and better-structured React applications with significantly less boilerplate code.

## Core Packages

```mermaid
graph TD;
    subgraph DD ["Migration Packages"]
        E["@suspensive/codemods"]
    end
    subgraph AA ["Core Packages"]
        A["@suspensive/react"]
    end
    subgraph BB ["Adapter Packages"]
        C["@suspensive/react-query"]
        D["@suspensive/jotai"]
    end
    subgraph CC ["Version-Specific Packages"]
        F["@suspensive/react-query-4"]
        G["@suspensive/react-query-5"]
    end

    A --> C
    A --> D
    C --> F
    C --> G
```

### Package Responsibilities

<br />

<Table>
  <thead>
    <Table.Tr>
      <Table.Th>Package</Table.Th>
      <Table.Th>Description</Table.Th>
      <Table.Th>Key Features</Table.Th>
    </Table.Tr>
  </thead>
  <tbody>
    <Table.Tr>
      <Table.Td>@suspensive/react</Table.Td>
      <Table.Td>Core suspense components</Table.Td>
      <Table.Td>ErrorBoundary, Suspense, Delay, ErrorBoundaryGroup</Table.Td>
    </Table.Tr>
    <Table.Tr>
      <Table.Td>@suspensive/react-query</Table.Td>
      <Table.Td>TanStack Query integration</Table.Td>
      <Table.Td>
        SuspenseQuery, SuspenseInfiniteQuery, Version detection
      </Table.Td>
    </Table.Tr>
    <Table.Tr>
      <Table.Td>@suspensive/jotai</Table.Td>
      <Table.Td>Jotai integration</Table.Td>
      <Table.Td>useAtomValue, useAtom, useSetAtom</Table.Td>
    </Table.Tr>
    <Table.Tr>
      <Table.Td>@suspensive/codemods</Table.Td>
      <Table.Td>Migration utilities</Table.Td>
      <Table.Td>Automated code transformations</Table.Td>
    </Table.Tr>
  </tbody>
</Table>

## Architecture and Component Relationships

The Suspensive ecosystem is built on a foundation of core components from @suspensive/react, which are then extended and specialized by other packages:

```mermaid
graph TD;
subgraph AA [Data Fetching @suspensive/react-query]
A[queryOptions];
B[infiniteQueryOptions];
C[useSuspenseQuery, SuspenseQuery];
D[useSuspenseInfiniteQuery, SuspenseInfiniteQuery];
E[useSuspenseQueries, SuspenseQueries];
end
subgraph BB [State Management @suspensive/jotai]
F[Atom];
G[AtomValue];
end
subgraph CC [Core Components @suspensive/react]
H[Suspense];
I[ErrorBoundary];
J[Delay];
K[ErrorBoundaryGroup];
end

C --> H;
D --> H;
E --> H;
F --> H;
G --> H;

A --> C;
A --> E;
B --> D;
```

## Version Support and Compatibility

Suspensive is designed to work with:

- React 18 and React 19
- TanStack Query v4 and v5
- Jotai v2

The library automatically adapts to the installed versions of these dependencies, providing a seamless developer experience regardless of which specific versions are being used in a project.

## Data Flow Pattern

A central pattern in Suspensive is the handling of asynchronous states through React Suspense. Here's how data flows through the system when using components like SuspenseQuery:

```mermaid
sequenceDiagram
    participant App as Application Component
    participant SQ as SuspenseQuery
    participant S as Suspense
    participant EB as ErrorBoundary
    participant TQ as TanStack Query
    participant API as External Data Source

    App ->> SQ: Render with query config
    SQ ->> TQ: Configure with suspense:true
    TQ ->> API: Fetch data

    alt [Loading]
        API -->> TQ: Still loading
        TQ -->> SQ: Throw promise
        SQ -->> S: Promise caught
        S ->> App: Render fallback UI
    end

    alt [Error]
        API -->> TQ: Error response
        TQ -->> SQ: Throw error
        SQ -->> EB: Error caught
        EB ->> App: Render error UI
    end

    alt [Success]
        API -->> TQ: Data response
        TQ -->> SQ: Return data
        SQ -->> App: Render with data
    end
```

## Key Benefits

- **Declarative Error Handling**: Replace try/catch blocks with component-based error boundaries
- **Simplified Data Fetching**: Integrate seamlessly with TanStack Query using suspense
- **Coordinated Error Management**: Group and reset multiple error boundaries together
- **Controlled Loading States**: Fine-tune loading indicators with timing controls
- **Viewport Awareness**: Trigger loading or animations based on viewport visibility

<TrustedBy />
